---
title: "Installation"
description: "The Modern Headless & Zero Runtime UI Component Library 🐻‍❄️✨"
---

import { Callout, Tabs, Tab, Steps } from "nextra-theme-docs";

# Installation

<Callout type="info">
  Kuma UI is compatible with React 18 and above. If you're using an older
  version of React, [you'll need to upgrade
  first](https://react.dev/blog/2022/03/08/react-18-upgrade-guide).
</Callout>

## Install packages

To install Kuma UI in your project, run one of the following commands in your terminal:

<Tabs items={["npm", "pnpm", "yarn"]} storageKey="selected-pkg-manager">
  {/* prettier-ignore */}
  <Tab>
  ```bash copy
  npm install @kuma-ui/core
  ```
  </Tab>
  {/* prettier-ignore */}
  <Tab>
  ```bash copy
  pnpm install @kuma-ui/core
  ```
  </Tab>
  {/* prettier-ignore */}
  <Tab>
  ```bash copy
  yarn add @kuma-ui/core
  ```
  </Tab>
</Tabs>

Once the `@kuma-ui/core` package is successfully installed, you can proceed to install a plugin for your specific framework (Next.js or Vite) as below.

<Tabs items={["Next.js", "Vite", "webpack"]} storageKey="selected-framework">
  {/* prettier-ignore */}
  <Tab>
  ```bash copy
  pnpm install -D @kuma-ui/next-plugin
  ```
  </Tab>
  {/* prettier-ignore */}
  <Tab>
  ```bash copy
  pnpm install -D @kuma-ui/vite
  ```
  </Tab>
  {/* prettier-ignore */}
  <Tab>
  ```bash copy
  pnpm install -D @kuma-ui/webpack-plugin
  ```
  </Tab>
</Tabs>

## Setting Up Kuma UI

Once you've installed the plugin, you need to configure it in your configuration file.

<Tabs
  items={["Next.js", "Vite", "webpack"]}
  storageKey="selected-config"
>
  {/* prettier-ignore */}
  <Tab>
    ```js filename="next.config.js"
    const { withKumaUI } = require("@kuma-ui/next-plugin");

    /** @type {import('next').NextConfig} */
    const nextConfig = {
      reactStrictMode: true,
    };

    module.exports = withKumaUI(nextConfig, {
      // The destination to emit an actual CSS file. If not provided, the CSS will be injected via virtual modules.
       outputDir: "./.kuma", // Optional
       // Enable WebAssembly support for Kuma UI. Default is false and will use Babel to transpile the code.
       wasm: true // Optional
    });
    ```

  </Tab>

{/* prettier-ignore */}
  <Tab>
    ```js filename="vite.config.js"
    import { defineConfig } from "vite";
    import react from "@vitejs/plugin-react";
    import KumaUI from "@kuma-ui/vite";

    export default defineConfig({
      plugins: [
        react(),
        KumaUI({
          // Enable WebAssembly support for Kuma UI. Default is false and will use Babel to transpile the code.
          wasm: true // Optional
        }),
      ],
    });
    ```

  </Tab>

{/* prettier-ignore */}
  <Tab>
    ```js filename="webpack.config.js"
    const KumaUIWebpackPlugin = require("@kuma-ui/webpack-plugin").default;

    module.exports = {
      plugins: [
        new KumaUIWebpackPlugin({
          // The destination to emit an actual CSS file. If not provided, the CSS will be injected via virtual modules.
          outputDir: "./.kuma" // Optional
          // Enable WebAssembly support for Kuma UI. Default is false and will use Babel to transpile the code.
          wasm: true // Optional
        }),
      ],
    };
    ```

  </Tab>
</Tabs>

## Server Side Rendering

If you are using Kuma UI with Next.js, setting up Server Side Rendering (SSR) isn't mandatory. However, without this setup, you may experience a Flash Of Unstyled Content (FOUC). **We highly recommend setting up SSR** to prevent this from happening.

<Tabs
  items={["Next.js App Router", "Next.js Pages Router"]}
  storageKey="selected-ssr"
>
  {/* prettier-ignore */}
  <Tab>
    ```tsx filename="app/layout.tsx"
    import { KumaRegistry } from "@kuma-ui/next-plugin/registry"

    export default function RootLayout({
      children,
    }: {
      children: React.ReactNode
    }) {
      return (
        <html>
          <body>
            <KumaRegistry>{children}</KumaRegistry>
          </body>
        </html>
      );
    }
    ```

  </Tab>
  {/* prettier-ignore */}
  <Tab>
    ```tsx filename="pages/_document.tsx"
    import Document, { Html, Head, Main, NextScript } from "next/document";
    import { createStyleRegistry, StyleRegistry } from "@kuma-ui/core";

    export default class MyDocument extends Document {
      static async getInitialProps(ctx: DocumentContext) {
        const registry = createStyleRegistry();
        const originalRenderPage = ctx.renderPage;

        try {
          ctx.renderPage = () =>
            originalRenderPage({
              enhanceApp: (App) => (props) =>
                (
                  <StyleRegistry registry={registry}>
                    <App {...props} />
                  </StyleRegistry>
                ),
            });

          const initialProps = await Document.getInitialProps(ctx);
          return {
            ...initialProps,
            styles: [initialProps.styles, registry.styles()],
          };
        } finally {
          registry.flush();
        }
      }

      render() {
        return (
          <Html>
            <Head />
            <body>
              <Main />
              <NextScript />
            </body>
          </Html>
        );
      }
    }
    ```

  </Tab>
</Tabs>

## Integrate with Storybook

For those looking to integrate Kuma UI with Storybook, the process will vary depending on the [Storybook builder](https://storybook.js.org/docs/react/builders/overview) you are using. Here's how you can set it up:

<Tabs
  items={["Next.js (webpack)", "Vite"]}
  storageKey="selected-storybook-builder"
>
  {/* prettier-ignore */}
  <Tab>
    If your project uses Storybook Webpack builder (including `@storybook/nextjs`), you can use `"@kuma-ui/webpack-plugin"`.

    ```ts copy
    // .storybook/main.ts

    import KumaUIWebpackPlugin from "@kuma-ui/webpack-plugin";

    // ...

    const config: StorybookConfig = {
      // ...
      webpackFinal: (config) => {
        config.plugins = [...(config.plugins ?? []), new KumaUIWebpackPlugin()];

        return config;
      },
      // ...
    };

    // ...
    ```

    For more information, refer to the [Working with Webpack plugins](https://storybook.js.org/docs/react/builders/webpack#working-with-webpack-plugins) section in the Storybook documentation.

  </Tab>
  {/* prettier-ignore */}
  <Tab>
    When using Storybook Vite builder, **Kuma UI might work without any specific configuration**, as the Vite builder reads from the `vite.config.js`.

    However, you may need to tweak some options or add a custom configuration. Here's a guide to help you:

    ### Specify Configuration Path

    You can define the path to your Vite configuration file using the `viteConfigPath` builder option.

    ```ts copy
    // .storybook/main.ts

    // ...

    const config = {
      framework: {
        name: "@storybook/react-vite",
        options: {
          builder: {
            viteConfigPath: ".storybook/customViteConfig.js",
          },
        },
      },
    };

    // ...
    ```

    ### Override Vite Config with `viteFinal`

    Use the `viteFinal` option add Kuma UI Vite plugin.

    ```ts
    // .storybook/main.ts

    import { mergeConfig } from "vite";
    import KumaUI from "@kuma-ui/vite";

    // ...

    const config = {
      async viteFinal(config, { configType }) {
        return mergeConfig(config, {
          plugins: [KumaUI()],
        });
      },
    };

    // ...
    ```

    For additional details and customization options, refer to the ["Customize Vite config" section of Storybook builder for Vite README](https://github.com/storybookjs/storybook/blob/next/code/builders/builder-vite/README.md#customize-vite-config).

  </Tab>
</Tabs>
